docs/PID tuning.md

   1 # PID tuning
   2
   3 Every aspect of flight dynamics is controlled by the selected "PID controller". This is an algorithm which is
   4 responsible for reacting to your stick inputs and keeping the craft stable in the air by using the gyroscopes and/or
   5 accelerometers (depending on your flight mode).
   6
   7 The "PIDs" are a set of tuning parameters which control the operation of the PID controller. The optimal PID settings
   8 to use are different on every craft, so if you can't find someone with your exact setup who will share their settings
   9 with you, some trial and error is required to find the best performing PID settings.
  10
  11 A video on how to recognise and correct different flight problems caused by PID settings is available here:
  12
  13 https://www.youtube.com/watch?v=YNzqTGEl2xQ
  14
  15 Basically, the goal of the PID controller is to bring the craft's rotation rate in all three axes to the rate that
  16 you're commanding with your sticks. An error is computed which is the difference between your target rotation rate and
  17 the actual one measured by the gyroscopes, and the controller tries to bring this error to zero.
  18
  19 ##PIDs
  20
  21 **The P term** controls the strength of the correction that is applied to bring the craft toward the target angle or
  22 rotation rate. If the P term is too low, the craft will be difficult to control as it won't respond quickly enough to
  23 keep itself stable. If it is set too high, the craft will rapidly oscillate/shake as it continually overshoots its
  24 target.
  25
  26 **The I term** corrects small, long term errors. If it is set too low, the craft's attitude will slowly drift. If it is
  27 set too high, the craft will oscillate (but with slower oscillations than with P being set too high).
  28
  29 **The D term** attempts to increase system stability by monitoring the rate of change in the error. If the error is rapidly converging to zero, the D term causes the strength of the correction to be backed off in order to avoid overshooting the target.
  30
  31
  32 ##TPA and TPA Breakpoint
  33
  34 Note that TPA is set via CLI or on the PID TUNING tab of the GUI.  tpa_breakpoint is set via CLI
  35
  36 Also note that TPA and tpa_breakpoint may not be used in certain PID Contorllers.  Check the description on the individual controller.
  37
  38 TPA applies a PID value reduction in relation to full Throttle. It is used to apply dampening of PID values as full throttle is reached.
  39
  40 **TPA** = % of dampening that will occur at full throttle.
  41
  42 **tpa_breakpoint** = the point in the throttle curve at which TPA will begin to be applied.
  43
  44 An Example: With TPA = 50 (or .5 in the GUI) and tpa_breakpoint = 1500 (assumed throttle range 1000 - 2000)
  45
  46 * At 1500 on the throttle channel, the PIDs will begin to be dampened.
  47 * At 3/4 throttle (1750), PIDs are reduced by approximately 25% (half way between 1500 and 2000 the dampening will be 50% of the total TPA value of 50% in this example)
  48 * At full throttle (2000) the full amount of dampening set in TPA is applied. (50% reduction in this example)
  49
  50 ![tpa example chart](https://cloud.githubusercontent.com/assets/1668170/6053290/655255dc-ac92-11e4-9491-1a58d868c131.png "TPA Example Chart")
  51
  52
  53 **How and Why to use this?**
  54
  55 If you are getting oscillations starting at say 3/4 throttle, set tpa breakpoint = 1750 or lower (remember, this is assuming your throttle range is 1000-2000), and then slowly increase TPA until your oscillations are gone. Usually, you will want tpa breakpoint to start a little sooner then when your oscillations start so you'll want to experiment with the values to reduce/remove the oscillations.
  56
  57 ## PID controllers
  58
  59 Cleanflight has 6 built-in PID controllers which each have different flight behavior. Each controller requires
  60 different PID settings for best performance, so if you tune your craft using one PID controller, those settings will
  61 likely not work well on any of the other controllers.
  62
  63 You can change between PID controllers by running `set pid_controller=n` on the CLI tab of the Cleanflight
  64 Configurator, where `n` is the number of the controller you want to use. Please read these notes first before trying one
  65 out.
  66
  67 ### PID controller 0, "MultiWii" (default)
  68
  69 PID Controller 0 is the default controller in Cleanflight, and Cleanflight's default PID settings are tuned to be
  70 middle-of-the-road settings for this controller. It originates from the old MultiWii PID controller from MultiWii 2.2
  71 and earlier.
  72
  73 One of the quirks with this controller is that if you increase the P value for an axis, the maximum rotation rates for
  74 that axis are lowered. Hence you need to crank up the pitch or roll rates if you have higher and higher P values.
  75
  76 In Horizon and Angle modes, this controller uses both the LEVEL "P" and "I" settings in order to tune the
  77 auto-leveling corrections in a similar way to the way that P and I settings are applied to roll and yaw axes in the acro
  78 flight modes. The LEVEL "D" term is used as a limiter to constrain the maximum correction applied by the LEVEL "P" term.
  79
  80 ### PID controller 1, "Rewrite"
  81
  82 PID Controller 1 is a newer PID controller that is derived from the one in MultiWii 2.3 and later. It works better from
  83 all accounts, and fixes some inherent problems in the way the old one worked. From reports, tuning is apparently easier
  84 on controller 1, and it tolerates a wider range of PID values well.
  85
  86 Unlike controller 0, controller 1 allows the user to manipulate PID values to tune reaction and stability without
  87 affecting yaw, roll or pitch rotation rates (which are tuned by the dedicated roll & pitch and yaw rate
  88 settings).
  89
  90 In Angle mode, this controller uses the LEVEL "P" PID setting to decide how strong the auto-level correction should
  91 be. Note that the default value for P_Level is 90.  This is more than likely too high of a value for most, and will cause the model to be very unstable in Angle Mode, and could result in loss of control.  It is recommended to change this value to 20 before using PID Controller 1 in Angle Mode.
  92
  93 In Horizon mode, this controller uses the LEVEL "I" PID setting to decide how much auto-level correction should be
  94 applied. The default Cleanflight setting for "I" will result in virtually no auto-leveling being applied, so that will
  95 need to be increased in order to perform like PID controller 0.
  96
  97 The LEVEL "D" setting is not used by this controller.
  98
  99 TPA is not used by this controller.
 100
 101 ### PID controller 2, "LuxFloat"
 102
 103 PID Controller 2 is Lux's new floating point PID controller. Both controller 0 and 1 use integer arithmetic, which was
 104 faster in the days of the slower 8-bit MultiWii controllers, but is less precise.
 105
 106 This controller has code that attempts to compensate for variations in the looptime, which should mean that the PIDs
 107 don't have to be retuned when the looptime setting changes.
 108
 109 There were initially some problems with horizon mode, and sluggishness in acro mode, that were recently fixed by
 110 nebbian in v1.6.0. The autotune feature does not work on this controller, so don't try to autotune it.
 111
 112 It is the first PID Controller designed for 32-bit processors and not derived from MultiWii.
 113
 114 The strength of the auto-leveling correction applied during Angle mode is set by the parameter "level_angle" which
 115 is labeled "LEVEL Proportional" in the GUI. This can be used to tune the auto-leveling strength in Angle mode compared to
 116 Horizon mode. The default is 5.0.
 117
 118 The strength of the auto-leveling correction applied during Horizon mode is set by the parameter "level_horizon" which
 119 is labeled "LEVEL Integral" in the GUI. The default is 3.0, which makes the Horizon mode apply weaker self-leveling than
 120 the Angle mode. Note: There is currently a bug in the Configurator which shows this parameter divided by 100 (so it
 121 shows as 0.03 rather than 3.0).
 122
 123 The transition between self-leveling and acro behavior in Horizon mode is controlled by the "sensitivity_horizon"
 124 parameter which is labeled "LEVEL Derivative" in the Cleanflight Configurator GUI. This sets the percentage of your
 125 stick travel that should have self-leveling applied to it, so smaller values cause more of the stick area to fly using
 126 only the gyros. The default is 75%
 127
 128 For example, at a setting of "100" for "sensitivity_horizon", 100% self-leveling strength will be applied at center
 129 stick, 50% self-leveling will be applied at 50% stick, and no self-leveling will be applied at 100% stick. If
 130 sensitivity is decreased to 75, 100% self-leveling will be applied at center stick, 50% will be applied at 63%
 131 stick, and no self-leveling will be applied at 75% stick and onwards.
 132
 133 ### PID controller 3, "MultiWii23" (default for the ALIENWIIF1 and ALIENWIIF3 targets)
 134
 135 PID Controller 3 is an direct port of the PID controller from MultiWii 2.3 and later.
 136
 137 The algorithm is handling roll and pitch differently to yaw. Users with problems on yaw authority should try this one.
 138
 139 For the ALIENWII32 targets the gyroscale is removed for even more yaw authority. This will provide best performance on very small multicopters with brushed motors.
 140
 141 ### PID controller 4, "MultiWiiHybrid"
 142
 143 PID Controller 4 is an hybrid version of two MultiWii PID controllers. Roll and pitch is using the MultiWii 2.2 algorithm and yaw is using the 2.3 algorithm.
 144
 145 This PID controller was initialy implemented for testing purposes but is also performing quite well.
 146
 147 For the ALIENWII32 targets the gyroscale is removed for more yaw authority. This will provide best performance on very small multicopters with brushed motors.
 148
 149 ### PID controller 5, "Harakiri"
 150
 151 PID Controller 5 is an port of the PID controller from the Harakiri firmware.
 152
 153 The algorithm is leveraging more floating point math. This PID controller also compensates for different looptimes on roll and pitch. It likely don't need retuning of the PID values when looptime is changing. Actually there are two settings hardcoded which are configurable via the GUI in Harakiri:
 154
 155         OLD_YAW 0 // [0/1] 0 = multiwii 2.3 yaw, 1 = older yaw.
 156         MAIN_CUT_HZ 12.0f // (default 12Hz, Range 1-50Hz)
 157
 158 The PID controller is flight tested and running well with the default PID settings. If you want do acrobatics start slowly.
 159
 160 Yaw authority is also quite good.
 161
 162
 163